Overview | Package | Class | Tree | Deprecated | Index | Help
| Oracle® OLAP Java API Reference 10g Release 2 (10.2) B14348-02
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## oracle.olapi.transaction
Interface TransactionProvider

All Known Implementing Classes:
  ExpressTransactionProvider

public interface TransactionProvider

This interface defines an OLAP transaction provider. The interface is not implemented by OLAP API application developers. The `ExpressTransactionProvider` class implements this interface for transactions with Oracle OLAP.

Creating a derived `Source` or changing the state of a `Template` occurs in a transaction context. A `TransactionProvider` ensures the following:

- A transaction is isolated from other transactions.
- If a transaction fails, its effects are undone (rolled back).
- The effects of a completed transaction persist.

A transaction is represented by an instance of the `Transaction` class. An application does not directly create new `Transaction` objects. Instead, a `TransactionProvider` supplies them as they are needed. Only one `Transaction` is the current `Transaction` at any one time. With the methods of a `TransactionProvider`, an application can get the current `Transaction` or set a previously saved `Transaction` as the current `Transaction`.

An application creates a derived `Source` or changes the state of a `Template` in the current `Transaction`. A `Source` or state change is active, or valid, in the `Transaction` in which in which it was created or modified, or in a child of that `Transaction`. Any changes that occur in the child `Transaction` do not take effect in the parent `Transaction` until the application calls the `prepareCurrentTransaction` and `commitCurrentTransaction` methods of the `TransactionProvider`. The only `Source` that can be modified is one produced by a `Template` and which therefore has a `DynamicDefinition` as a proxy for the `ImmutableDefinition` that is paired with the `Source`.

When the application calls the `commitCurrentTransaction` method, the state of the child `Transaction` moves up into the parent `Transaction`. The child `Transaction` disappears. The updated `Transaction` is still the parent `Transaction` for any other child `Transaction` of the original parent `Transaction`. If the application does not want to commit a child `Transaction` into the parent `Transaction`, then it can call the `rollbackCurrentTransaction` method. The `TransactionProvider` then discards any changes made in the child `Transaction` and makes the parent `Transaction` the current `Transaction`.

The following example illustrates a rollback.

     TransactionProvider transactionProvider = new ExpressTransactionProvider();
     // Save the top-level Transaction.
     Transaction parent = transactionProvider.getCurrentTransaction();
     // Begin a child Transaction.
     transactionProvider.beginSubtransaction();

     // The createCube() method returns a Source that was produced by a Template.
     // That Source represents the joining of a measure and some dimensions into a cube.
     // The context input parameter is an object that supplies a MetadataProvider and a
     // DataProvider for the cube Template to use to get primary Source objects and
     // derived Source objects.

     // Create a cube in the child Transaction.
     Source cube = createCube(context);
     // Save the child Transaction.
     Transaction child = transactionProvider.getCurrentTransaction();
     // Begin a grandchild Transaction.
     transactionProvider.beginSubtransaction();
     // Add another dimension as an edge.
     cube.addEdge(edge);
     // Discard the grandchild Transaction that added the edge.
     transactionProvider.rollbackCurrentTransaction();
     // Prepare and commit the child Transaction.
     transactionProvider.prepareCurrentTransaction();
     transactionProvider.commitCurrentTransaction();
     // The cube now exists in the parent Transaction.

A transaction is represented by one of the following two types of OLAP API `Transaction` objects:

- A read `Transaction`, in which an application can create a `Cursor` to fetch the data defined by a `Source`. The initial `Transaction` in an application is a read `Transaction`.
- A write `Transaction`, in which an application creates a derived `Source` or changes the state of a `Template`. A write `Transaction` is a child of a parent read `Transaction`. To move a `Source` or state change created in a write `Transaction` into its parent read `Transaction`, the application must call the `prepareCurrentTransaction` and `commitCurrentTransaction` methods.

The type of `Transaction` is not usually visible to an application. However, you should be aware of the types because some exceptions, such as `WriteLockException`, refer to the `Transaction` type.

The following is an example of how a `TransactionProvider` uses read and write `Transaction` objects.

- An application creates a derived `Source` by joining two primary `Source` objects.
- When the `join` call occurs, the `TransactionProvider` provides the current `Transaction`.
- Since this is the first operation that creates a derived `Source`, the type of `Transaction` is unassigned. The `TransactionProvider` makes it a read `Transaction`, `transactionA`.
- Since the `join` call creates a derived `Source`, `sourceA`, the application needs a write `Transaction`. The `TransactionProvider` creates a child `Transaction`, `transactionB`, of `transactionA`. The `TransactionProvider` makes `transactionB` a write `Transaction`.
- The application joins `sourceA` to a primary `Source` to create another derived `Source`, `sourceB`. Since the current `Transaction` is a write `Transaction`, this second join occurs in the same `Transaction`.
- The application then calls the `prepareCurrentTransaction` and `commitCurrentTransaction` methods. The state of child `Transaction`, `transactionB`, now moves up into the parent `Transaction`, `transactionA`. The `transactionB` `Transaction` disappears, leaving `transactionA` as the current `Transaction`. The `Source` objects created in `transactionB` are now active in `transactionA`.
- Since `transactionA` is a read `Transaction`, the application can create a `Cursor` for `sourceA` or `sourceB`, get the values from the `Cursor`, and display the data.

See Also:
  `Cursor`, `Source`, `Template`

Method Summary
`void` | `addTransactionListener( l)` Registers a `TransactionListener` with this `TransactionProvider`.
`Transaction` | `beginSubtransaction()` Begins a child `Transaction` of the current `Transaction`.
`void` | `commitCurrentTransaction()` Moves the state of a child `Transaction` into the parent `Transaction`.
`Transaction` | `getCurrentTransaction()` Gets the current `Transaction`.
`void` | `prepareCurrentTransaction()` Prepares the current `Transaction` for committing.
`void` | `removeTransactionListener( l)` Unregisters a `TransactionListener` with this `TransactionProvider`.
`void` | `rollbackCurrentTransaction()` Rolls back, or undoes, any OLAP API operations the application performed in the current `Transaction`.
`void` | `setCurrentTransaction(Transaction transaction)` Specifies a `Transaction` as the current `Transaction`.

Method Detail

### getCurrentTransaction

    public Transaction getCurrentTransaction()

  Gets the current `Transaction`.
  Returns:
    The current `Transaction`.

### setCurrentTransaction

    public void setCurrentTransaction(Transaction transaction)

  Specifies a `Transaction` as the current `Transaction`.
  Parameters:
    `transaction` - A `Transaction` object to specify as the current `Transaction`.

### prepareCurrentTransaction

    public void prepareCurrentTransaction()
                                   throws NotCommittableException,
                                          TransactionInactiveException

  Prepares the current `Transaction` for committing. An application must call `prepareCurrentTransaction` before calling `commitCurrentTransaction`.

### commitCurrentTransaction

    public void commitCurrentTransaction()
                                  throws NotPreparedException,
                                         TransactionInactiveException

  Moves the state of a child `Transaction` into the parent `Transaction`. Before calling `commitCurrentTransaction`, an application must call `prepareCurrentTransaction`.

### rollbackCurrentTransaction

    public void rollbackCurrentTransaction()
                                    throws NotPreparedException,
                                           TransactionInactiveException

  Rolls back, or undoes, any OLAP API operations the application performed in the current `Transaction`. The `TransactionProvider` discards the operations the application performed in the child `Transaction` and makes the parent `Transaction` the current `Transaction`.

### beginSubtransaction

    public Transaction beginSubtransaction()
                                    throws TransactionInactiveException

  Begins a child `Transaction` of the current `Transaction`. The child `Transaction` becomes the current `Transaction`.
  Returns:
    A `Transaction` object that represents the current `Transaction`.

### addTransactionListener

    public void addTransactionListener( l)

  Registers a `TransactionListener` with this `TransactionProvider`.
  Parameters:
    `l` - The `TransactionListener` to add to this `TransactionProvider`.

### removeTransactionListener

    public void removeTransactionListener( l)

  Unregisters a `TransactionListener` with this `TransactionProvider`.
  Parameters:
    `l` - The `TransactionListener` to remove from the list of listeners for this `TransactionProvider`.

Overview | Package | Class | Tree | Deprecated | Index | Help
| Oracle® OLAP Java API Reference 10g Release 2 (10.2) B14348-02
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2002, 2005, Oracle. All rights reserved.